Certified message delivery and queuing in multipoint publish/subscribe communications

ABSTRACT

A method for certified delivery of an outgoing message or messages in a multipoint anonymous, publish/subscribe telecommunications system. The system for utilizing the method and program product is one having at least one publisher ( 10 ) and at least one subscriber ( 20 ). The method is carried out by first establishing a certified delivery session ledger. Next each outgoing message is labeled with a label including the delivery session name and a sequence number. The labeled outgoing message or messages are then sent to subscribers, and received by a subscriber. Various protocols are described.

BACKGROUND TO THE INVENTION

1. Technical Field

This invention relates to multipoint publish/subscribe communicationsand, more particularly, to certified message delivery and queuingbetween multipoint computer-based publisher and subscriber applications.

BACKGROUND

In a typical anonymous public/subscribe technologies—such as describedin U.S. Pat. Nos. 5,557,798; 5,339,392; 5.257,369 and 5,187,787—apublisher application publishes information to requesting or subscriberapplications without having any knowledge of the number, identity oraddress of any such subscriber applications. In fact, no subscriberapplications may exist. Instead of knowing about subscribers, apublisher will merely publish information applying a context or subject“label” to the published message. A subscriber then identifies desiredmessages by the content label and receives only those messages relevantto the desired content

The advantages of such a publish/subscribe, content-based addressingsystems are well known and include the ability to decouple subscribersand publishers from one another. This decoupling allows publishers andsubscribers to operate without having any knowledge of the identity,location or address, or communication protocols of each other. Theflexibility that this offers is enormous and, accordingly, suchcontent/subject-based addressing communication-enviroments are becomingincreasingly popular.

Unfortunately, the very advantages (such as anonymous decoupling) ofthese systems, precludes the use of conventional reliable messagingprotocols such as TCP. TCP, and other reliable messaging protocols applyonly in point-to-point type of communications. In these point-to-pointcommunications message senders and receivers are directly linked to oneanother and therefore know each other's addresses and locations.

Unfortunately, these reliable messaging protocols—that guarantee arrivaland order of arrival of messages—require advance knowledge betweenapplications. They are, therefore, not applicable to typicalpublish/subscribe environments.

Yet, such reliable or certified delivery of messages is extremelyimportant. For example, certified delivery is appropriate when a sendingapplication requires individual confirmation of delivery for eachmessage it sends. For example, a travelling sales representativecomputes sales figures on a lap-top computer, and sends them to asupervisor at the office. The user must know for certain that the datahas arrived, and has been included in the supervisor's sales report.

Certified delivery is also appropriate when a receiving applicationcannot afford to man any messages. For example, in an application thatprocesses orders to buy and sell inventory items, each order isimportant. If any orders are omitted, then inventory records areincorrect

In addition, certified delivery is appropriate when each message on aspecific subject builds upon information in the previous message withthat subject. For example, a sending program updates a receivingdatabase, contributing part of the data in a record, but leaving otherparts of the data unchanged. The database is correct only if all updatesarrive in the order they are sent.

Furthermore, certified delivery is appropriate in situations ofintermittent physical connectivity—such as discontinuous networkconnections, for example, an application in which several mobile lap-topcomputers must communicate with one another. Connectivity between mobileunits is sporadic, requiring persistent storage of messages until theappropriate connections are reestablished.

Thus, a very real need exists for having both the advantages ofcertified messaging and the advantages of content-based, anonymouspublish/subscribe environments.

SUMMARY OF THE INVENTION

Briefly, according to this invention a publisher publishes a message toany number of unknown subscribers. Note, as used herein “publisher” and“sender” are used synonymously, and “subscriber” and “listener” are usedsynonymously. The message is published indicating the subject or contentusing typical content-based publish/subscribe protocols. Subscribersinterested in receiving information on the designated content receivethe message without knowing about the publisher. Thus the publisherinformation remains transparent to the subscriber.

In circumstances where the certified messaging is required, theinvention provides for establishing a message delivery tracking session.This session includes a name and a ledger used for tracking.

Using these functions the system can track delivery of messages andnotify publishers/senders if messages are not delivered. In oneembodiment of the invention, delivery attempts are repeated for a presettime (or number of delivery attempts) to ensure or attempt to ensuredelivery.

This invention also extends to queuing messages for certified delivery.This occurs when certified delivery is required for a one of a group ofn possible recipients. The system ensures that one (and not all) of thegroup receives the message. This is accomplished by having members ofthe group indicate their availability or capacity and having the systemroute the message to the subscriber (listener) with the greatestavailability.

An extension of this concept is the scheduling of tasks for a group of npossible task performers, each available to accomplish a task. Each taskdoer, notifies the system of its availability/ability to accomplishtasks. Tasks are then sent to/queued for each task doer according to arating based on its availability.

ADVANTAGES OF THE INVENTION

This invention has a number of advantages. For example, it provides:

Certainty

-   -   Certified delivery assures application programs that every        message reaches each intended recipient—in the order sent. When        delivery is not possible, both senders and optionally, listeners        receive explicit information about each undelivered message.

Convenience

-   -   Once a program sends a certified message, the system continues        delivery attempts until delivery succeeds, or until the        message's time limit expires.

Control

-   -   Application programs determine an explicit time limit for each        message.    -   Sending applications can disallow certified delivery to specific        listening sessions.

Detail

-   -   The system can also present advisory messages to inform        application programs of every significant event relating to        delivery.

Process-Based or File-Based Recording

-   -   The system can also record the status of each message in a        ledger. Applications that require certification only for the        duration of the application    -   process can choose a process-based ledger. Applications that        require certification that    -   trends process termination and restart can choose a file-based        ledger.

The invention will be described in grater detail below with reference tothe accompanying drawings.

DESCRIPTION OF THE DRAWINGS

In the attached drawings:

FIG. 1 is a schematic representation of a typical publish/subscribeenvironment useful for illustrating this invention; and

FIG. 2 is a schematic representation of a typical publish/subscribeenvironment useful in illustrating the distributed queuing and taskscheduling aspects of the invention.

SPECIFIC DESCRIPTION

Overview

FIG. 1 shows a publisher application (sender) 10 and a plurality ofsubscriber applications (listeners) 20, 20′ and 20″. In the preferredembodiment of this invention the publisher and subscriber(s) aresoftware applications based on one or more computers interconnected by anetwork 30 providing a data path among the applications. The publisher10 and subscriber(s) 20 preferably implement a content-basedcommunications protocol whereby a publisher publishes a messageindicating only the content of the message and without knowing theidentity or protocols used by the subscriber(s) 20. Theseinter-application communications are established by communicationsdaemons 12 (associated with a publisher/sender) and 22, 22′ and 22″(associated with the subscriber/listener 20, 20′ and 20″). Thearrangement shown in this figure is well known and described in manypublications including the patents referred to above.

As is described in much greater detail below, a listener 20 can registerwith a specific publisher 10 to receive certified messages. Thiscommunication includes the subscribers name, its “inbox” address and thesubject/content of messages it requires information on. Thus thepublisher 10 will have a list of subscriber names and inboxes (but knownothing else about the subscriber) for all subscribers wishing toreceive certified messages. The publisher/sender 10 will thereforeexpect an acknowledgement of each message it sends out; anacknowledgement it would receive from a subscriber/listener 20, 20′and/or 20″. Importantly, if the publisher/sender 10 does not receive theacknowledgement, it sends an acknowledgement request message, usuallyfor a predetermined time or number of “sends.”

In the event the subscriber wishes to have guaranteed delivery ofmessages, the publisher can save the message to disk (or other storage)until an acknowledgement of subscriber receipt occurs. Thus, untilmessage times out, the subscriber can, at a later date, receive themessage by contacting the publisher. This would usually happen wheremessages are very dependent on their sequence or build upon priormessage. In these circumstances missing/unreceived messages could becatastrophic. Also, in these (and in most certified messagingapplications of this invention) each certified message is assigned atracking number. This allows both sender and listener/subscriber tomonitor which messages are received and/or missing.

In many applications, data communications are highly reliable, but insome situations applications were even stronger assurances of delivery.Certified delivery features offers greater certainty of delivery even insituations where processes and their network connections are unstable.

Certified Messaging

Enabling a Delivery-Tracking Session

The first step toward certified delivery is to enable adelivery-tracking session. A delivery-tracking session begins as anordinary anonymous publish/subscribe session; enabling a session addsinformation so that it can participate in certified delivery protocols.The additional information includes a name and a ledger.

Delivery-tracking sessions can send and receive messages, just asordinary sessions can. In addition, delivery-tracking sessions canparticipate in certified delivery calls (that is, calls in the rvcmlibrary layer); ordinary sessions cannot participate in these calls.(Notice the asymmetry. Delivery-tracking sessions can participate inordinary calls, but ordinary sessions cannot participate in certifieddelivery calls.)

Name

Each delivery-tracking session has a name which may be reusable, ornon-reusable. The name identifies the session to other delivery-trackingsessions, and is part of the label that identifies outbound messagesfrom the session.

A name is reusable when a program supplies it explicitly to the enablingcall. When a session with a usable name also has a file-based ledger, itoperates as instance of a persistent correspondent-which allowscontinuity of certified delivery beyond session termination and programrestarts.

Two delivery-tracking sessions must not bind the same reusable name thatis, at any moment in time, each reusable name must be unique. Sessionsmay reuse a name sequentially, but not simultaneously. Violating thisrule can significantly obstruct certified delivery. Typically, sessionnames have the same syntax as subject names.

Programs may omit a name in the enabling call-in which case the callgenerates a unique, non-reusable name for the session. No other sessionon any computer can ever have the same name. As a result, a session witha non-reusable name operates as a transient correspondent—no subsequentsession can continue the certified delivery behavior of the session.

Enabling a delivery-tracking session crates a ledger for it. Certifieddelivery software uses the ledger to record information about everyunresolved outbound certified message, every subject for which thissession receives (inbound) certified messages, and other cooperatingdelivery-tracking sessions.

Programs may store the ledger in a ledger file, or in process-basedstorage within the running program. (Even when a session uses a ledgerfile, it may sometimes replicate parts of the ledger in process-basedstorage for efficiency; however, programmers cannot rely on thisreplication.)

Ledger files must be unique. That is, two sessions must not use the sameledger file (concurrently). If an operating system supports raw diskdevices (also called raw partitions), a device can be specified as theledger file.

A session with a file-based ledger and a reusable name qualifies as apersistent correspondent, with certified delivery behavior that canextend beyond session termination.

Labeled Message

A labeled message is like an ordinary message, except that it includessupplementary information, which delivery-tacking sessions can use forcertified message delivery:

-   -   The name of the delivery-tracking session that sent the message.    -   A sequence number assigned by the sending session.

Sending a Labeled Message

Any delivery-tracking session can send a labeled message by using thesending calls in the certified message delivery library layer. Examplesof such delivery-Tracking Send Calls are in the table below. C rvcm_Send( ), rvcm_SendWithReply ( ) C++ RvCmSender:: certifiedSend ( ),RvCmSender:: certifiedSendRequest ( ) Java RvCmSender. certifiedSend (), RvCmSender. certifiedSendRequest ( )

Receiving a Labeled Message

For clarity, two kinds of listening endpoints are distinguished. Anordinary listener is a listener created with an ordinary listening call,such as the C functions rv_ListenInbox ( ) or rv_ListenSubject ( ). Adelivery-tracking listener is a listener created with adelivery-tracking listening call, such as the C functionsrvcm_ListenInbox ( ) or rvcm_ListenSubject ( )

Either type of listening endpoint can receive a labeledmessage-delivery-tracking listeners (created by the certified deliverylibrary), as well as ordinary listeners.

When an ordinary listener receives a labeled message, it presents it tothe appropriate callback function as if it were an ordinary message.That is, it ignores the supplementary information that distinguishes alabeled message.

When a delivery-tracking listener receives a labeled message, itsbehavior depends on context:

-   -   If a delivery-tracking listener is registered for certified        delivery, it presents the supplementary information to the        callback function.    -   If a delivery-tracking listener is not registered for certified        delivery, it presents a “null”    -   sender's name to the callback function, with a sequence number        of zero.

In addition, if appropriate, the certified delivery libraryautomatically requests that

-   -   the sender register the listener for certified delivery.

Discovery and Registration for Certified Delivery

Discovery

When a delivery-tracking listener receives a labeled message from adelivery-tracking sender that is not listed in the listener's ledger,the listener “discovers” the sender on the message subject.

Three events follow discovery:

-   -   Certified delivery software adds the sender's name to the        listener's ledger, as a source of messages on the subject.    -   Certified delivery software in the listening program contacts        the sending program to request registration for certified        delivery of the subject and information regarding the agreement.    -   Certified delivery software presents a REGISTRATION. DISCOVERY        advisory to the listening program.

Registration

When a delivery-tracking sender receives a registration request from adelivery-tracking listener, the sender automatically accepts therequest. Acceptance consists of these four events:

-   -   Certified delivery software registers the listener for certified        delivery of the subject—recording that fact in the sender's        ledger.    -   Certified delivery software in the sending program notifies the        listener session that the registration requested is accepted—the        sender accepts responsibility for certified delivery on the        subject.    -   Certified delivery software presents a REGISTRATION. REQUEST        advisory to the sender session, informing it of the new        registered listener.    -   When the certified delivery software in the listening program        receives the acceptance reply, it presents a REGISTRATION        CERTIFIED advisory to the listener session.

Certified Delivery Agreement

Following registration and acceptance, the sender and listener have acertified delivery agreement on the subject

-   -   The sender is responsible to record each outbound message on        that subject, and to retain the message in its ledger until it        receives confirmation of delivery from the listener (or until        the time limit of the message expires).    -   In return, the listener is responsible to confirm delivery of        each message, and to request retransmission when a message        arrives out of sequence.

The system arranges all of this accounting automatically. The sendingand listening programs do not participate directly in theseprotocols—only indirectly, by sending and listening with certifieddelivery library calls.

Notice that a certified delivery agreement applies in one directiononly—from a sender to a lists A two-way conversation requires twoseparate certified delivery agreements.

We refer to the two participants in a certified delivery agreement as acertified sender and a certified listener, and the labeled messages thatflow between them are certified messages. Notice the subtle differencein terminology—before establishing a certified delivery agreement, theparticipants are delivery-tracking senders and listeners; afterward,they are certified senders and listeners. A labeled message is only acertified message when the sender and receiver maintain a certifieddelivery agreement.

Delivering a Certified Message

Once a delivery agreement is in place, all subsequent messages on thesubject (from the certified sender to the certified listener) arecertified messages. Each certified message generates a series ofprotocol events:

-   -   When the system presents a certified message to the listening        callback function, it includes the sequence number assigned        (automatically) by the sending Software and the publisher's        name.    -   When the callback function returns, certified delivery software        automatically confirms delivery to the sender and records        confirmation to a ledger. (Programs can override this behavior        and confirm delivery explicitly.)    -   When confirmation reaches the sending program, certified        delivery software records delivery in the sender's ledger, and        presents a DELIVERY.CONFIRM advisory to the sender session.    -   When confirmation has arrived from every certified listener for        this message, certified delivers software deletes the message        from the sender's ledger, and presents a DELIVERY.COMPLETE        advisory to the sender session

Automatic Confirmation of Delivery

The default behavior of certified listens is to automatically confirmmessage delivery upon return from the data callback function. Programscan selectively override this behavior for specific listening endpoints(without affecting other listening endpoints).

By overriding automatic confirmation, the listener assumesresponsibility for explicitly confirming each inbound certified message.

Consider overriding automatic confirmation when processing inboundmessages involves asynchronous activity, such as computations in otherthreads, database queries, or additional network communications.

Requesting Confirmation

If a certified sender does not receive prompt confirmation of deliveryfrom a certified listener (for example, because of network glitches),the system in the sending program automatically requests confirmation.After each request, it presents a DELIVERY. NO_RESPONSE advisory to thesending session.

When a listener receives a request for confirmation, it checks itsledger, and reconfirms receipt of the messages that it has alreadyconfirmed. (This behavior is identical whether the program usesautomatic confirmation, or overrides it.)

Sequencing and Retransmission

A delivery-tracking sender assigns sequence numbers serially for eachoutbound subject, so the sequence numbers reflect the order of messagesfrom a sender on a specific subject.

When certified delivery software presents certified messages to acertified listener, it preserves the sequence in which the sender sentthem. If a message arrives out of sequence, certified delivery softwarein the listener does not present it to the callback function until allthe preceding messages are available.

For example, a certified listener is receiving certified delivery forthe subject FOO from a sender med BAZ. After receiving and presentingmessage number 32, the next message to arrive is message 35. Certifieddelivery software holds message 35 until it can first present messages33 and 34.

Meanwhile, the certified delivery software in FOO requestsretransmission of messages 33 and 34 from Baz. In a case where the timelimit on those messages has expired—so BAZ no longer has them in itsledger—certified delivery software presents a DELIVERY.UNAVAILABLEadvisory to the listener, indicating that messages 33 and 34 are nolonger available. Then it presents message 35 to the data callbackfunction.

Persistent Correspondents

We introduced the concept of persistent correspondents in the sectionName, page ] 44. A reusable name and a file-based ledger allow apersistent correspondent to continue certified delivery beyond thetermination and restart of a session or process.

EXAMPLE

Consider an example application systems in which application program JOEgenerates important information, and sends it to application program SUEin certified messages on the subject REMEMBER.THIS. Upon receipt, SUEstorm the information in a database.

If either JOE or SUE terminate unexpectedly, it is crucial thatcertified messages still arrive for entry into the database. To ensurethis result, both programs must represent persistent corrspondent-thatis, both programs enable sessions with reusable names (JOE _(—) PC andSUE _(—) PC), and each program keeps a file-based ledger. In addition,SUE requires old messages when it enables the Anon SUE _(—) PC.

During operation, JOE has sent message number 57 on the subjectREMEMBER.THIS but has not yet received delivery confirmation formessages 53-56. SUE is processing message 53, when a sudden hardwarefailure causes to terminate. Meanwhile, JOE continues to send messages58-77.

The computer restarts, and SUE restarts. The ledger file for SUE _(-—)PC indicates that message 52 was received and confirmed for the subjectREMEMBER.THIS a given publisher as JOE _(—) PC. On restart SUE _(—) PCwill contact JOE _(—) PC and reestablish their certified deliveryagreement When JOE accepts, JOE _(—) PC sits the stored messages 53-77on that subject.

In the above scenario it is important to notice the following:

That SUE does not miss any REMEMBER.THIS messages. However, the new SUEmust gracefully fix any difficulties caused by partial processing ofmessage 53 by the old SUE. JOE and SUE communicate using a broadcastsubject name not an inbox. Inbox names are unique, so they cannotcontinue beyond session termination and restart.

Anticipating a Listener

In some situations, a delivery-tracking sender can anticipate therequest for certified delivery from a persistent correspondent that hasnot yet begun listening.

Consider an example in which a database program (DB) records allmessages with the subject STORE.THIS. The program DB enables a sessionthat instantiates a persistent correspondent named DB _(—) PC. Allprograms that send messages with the subject STORE.THIS depend on thisstorage mechanism.

One such sending program is JAN. Whenever JAN starts, it can anticipatethat DB _(—) PC will request certified delivery of the subject STORE_(—) THIS. Suppose that JAN starts, but DB is not running, or a networkdisconnect has isolated JAN from DB. Anticipating that it willeventually receive a registration request for STORE.THIS from DB _(—)PC, JAN makes an add listener call. The effect is that the softwarewithin JAN behaves as if it has a certified delivery agreement with DB_(—) PC for the subject STORE.THIS. It stores outbound messages (on thatsubject) in its ledger. When DB restarts, or the network reconnects. JANautomatically retransmits all the stored messages to DB.

Cancelling Certified Delivery

Both listeners and senders can cancel a certified delivery agreement.

Listeners cancel by closing the listening endpoint, using calls listedbelow. Senders with certified delivery agreements to the closed endpointreceive REGISTRATION.CLOSED advisories. HOST.LISTEN.STOP advisoriesinform other applications of the change.

Senders can cancel certified delivery of a specific subject to aspecific listener. The sender program deletes from its ledger allinformation about delivery of the subject to the listener. The sendingprogram receives a REGISTRATION.CLOSED advisory. If the listeningcorrespondent is available (running and reachable), it receives aREGISTRATION.NOT _(—) CERTIFIED advisory. (Unlike the disallow listenercalls in Table 7, these calls do not cause denial of subsequentregistration requests.)

Disallowing Certified Delivery

As described before senders automatically accept all registrationrequests. This is true except when the sending program explicitlydisallows certified delivery to a listening session. Calls that disallowa listener cancel existing certified delivery agreements with thelistener session (on all subjects), and cause certified deliverysoftware to automatically deny subsequent registration requests from thelistener session.

When a sender has disallowed a listener, the events connected withregistration do not occur. Instead, certified delivery software in thesender notifies the listener session that the request is disallowed.When certified delivery software in the listening program receives therejection notice, it presents a REGISTRATION.NOT _(—) CERTIFIED advisoryto the listening session.

Allow listener calls supersede the effect of a previous disallowlistener call, allowing subsequent registration requests from thelistener session to succeed.

No Response to Registration Request

It is possible that a registration request never reaches thedelivery-tracking sender, or the acceptance notice never reaches thelistening program (for example, because of network glitches, ortermination of the sending program). After repeated attempts to registerwithout response from the sender, certified delivery software in thelistening program presents a REGISTRATION.NO _(—) RESPONSE advisory tothe listening session. After several attempts to register with noresponse, the listener stops sending requests.

Reusable Names

Sessions that represent persistent correspondents require reusablenames. Reusable names must obey the syntax for subject names. Reusablenames must not contain wildcard characters. Reusable names may not beginwith reserved elements (such as _(—) INBOX, _(—) RV or _(—) LOCAL). Forbest performance, reusable names should be kept short—only a fewcharacters, typically no more than three or four elements, and no morethan 50 characters in total.

Ledger Storage Mode

Each delivery-tracking session records information in a ledger, whichoccupies storage space within the application Process. A session thatrepresents a persistent correspondent must also keep a copy of theledger in a file. The file-based ledger preserves certified deliveryinformation beyond session (or process) termination and restart.

This feature has two associated costs:

-   -   The ledger file consumes disk space.    -   The application program pauses to update the ledger file at each        significant event

Transient correspondents need not pay these costs, because they do notuse ledger files. However, keeping the ledger in process-based storageconsumes process memory.

Ledger Size

The size of the ledger depends on several factors—the most important ofwhich is the retention rate of stored data. That is, the ledger growsfastest in response to the cumulative length of incompletely deliveredmessages.

Program developers can estimate the expected size of the ledger, andmust ensure that the process can allocate sufficient memory to containit For a file-based ledger, ensure that sufficient disk space isavailable as well, as memory requirements for the process applicationchange when utilizing a file-based ledger.

Event Manager

The system's certified delivery depends on the event manager for timerand I/O events. When an application enables a delivery-tracking session,that session must be an event-managed session.

No Synchronous Sessions

Synchronous sessions are not valid for certified delivery calls and alldelivery-tracking sessions must be asynchronous, event-managed sessions.

Distributed Queues

The system also provides use of distributed queues for one-of-ncertified delivery. In particular, the system provides for distributedqueueing of messages along with certified/guaranteed delivery in a“one-of-n” delivery mechanism. This delivery mechanism is illustrated inFIG. 2 in which a single publisher 202 is publishing messages to threeregistered subscribers 204, 206 and 208 respectively. One of thesubscribers, 206 is a large group of n-subscribers.

Distributed queueing addresses the problem that it is undesirable forall n-subscribers in registered subscriber 206 to get every messagepublished by publisher 202. For example, it may be undesirable becauseeach of the n-subscribers in group 206 will take an action. In addition,if each subscriber is to receive the message (and possibly respond toit) this will consume additional network bandwidth

Nonetheless, it is imperative (hence the need for certified guaranteeddelivery) for at least one of the n-subscribers in group 206 to receivethe message. I.e., ideally the system should deliver the message to onlyone of the n-subscribers 206. This type of situation arises where alarge number n of subscribers 206 is required to provide the desiredlevel of fault tolerance and/or load balancing. Fault tolerance isimportant in situations where applications may be unstable or messagedelivery is absolutely critical.

In the system of the invention, each subscriber application in the group206 operates by sending messages to another of the n-subscribers in thegroup 206 acting as a scheduler giving an indication of its weight. Thescheduler then responds by sending the message to the particularsubscriber in the group with the greatest weight. Greater details of howthis is accomplished follow directly below.

Accordingly, a distributed queue of subscribing database servers 206 canaccept certified message that represent tasks (updates and queries). Thesystem assigns each task to exactly one of the servers, while the groupof servers and the distribution of tasks remains completely transparentto the client processes.

Queue Members

The member sessions of a distributed queue all share the same reusablecorrespondent name indicating that they are members of the queue withthat name. Each member of a distributed queue listens for the samesubjects--yet even when n members listen, for each inbound message (ortask), only one member processes the message.

Member Roles-Worker and Scheduler

As used herein with respect to queueing and queued delivery, the terms“listener” and “worker” are used interchangeably. Each distributed queuemember session can have two distinct roles—as a worker, and as apotential scheduler.

In the listener or worker role, queue member sessions support a limitedsubset of certified delivery calls; members can listen to a subject,override automatic confirmation of delivery and confirm delivery. Queuemember sessions do not support any other certified delivery calls (inparticular, calls associated with sending certified messages). However,they do support all standard calls (for example, sending ordinarymessages).

The system includes fault tolerance software that maintains exactly oneactive scheduler in each queue; if the scheduler process terminates,another member assumes the role of scheduler. The queue member sessionin the scheduler role assigns inbound tasks to listeners in the queue.(A scheduler can assign tasks to its own listener component, but onlydoes so when all other listeners are busy.)

The Scheduler as a Fault-Tolerant Component

Although any queue member has the potential to become the scheduler,fault tolerance software maintains exactly one scheduler at all times.Fault tolerance parameters guide the software to select the most suitedmember as scheduler.

Scheduler weight represents the ability of a member session to fulfillthe role of scheduler, relative to other members of the same queue,i.e., the greatest availability or unused member resources. The queuemembers use relative scheduler weight values to elect one member as thescheduler; members with higher scheduler weight take precedence.

The active scheduler sends heartbeat messages at the interval specifiedby the user. Heartbeat messages inform other members that a member isacting as the scheduler. All sessions in the queue must specify the samescheduler heartbeat interval.

In addition, all sessions in the queue must specify the same scheduleractivation interval. When the heartbeat signal from the scheduler hasbeen silent for this interval the queue member with the greatestscheduler weight takes its place as the new scheduler.

Assigning Tasks to Workers

The scheduler assigns each task to a worker or listener (another queuemember session). That worker or listener alone processes the taskmessage in a data callback function.

Worker Weight

Relative worker or listener weights assist the scheduler in assigningtasks. When the scheduler receives a task, it assigns the task to theavailable worker or listener with the greatest worker or listenerweight.

Enabling a session as a queue member tacitly sets its worker or listenerweight parameter to 1. That is, all members implicitly have the sameworker or listener weight, unless program code explicitly changes theworker or listener weight.

Availably

When the scheduler receives a task, it assigns the task to the availableworker listener with the greatest listener weight.

A worker listener is considered available unless either of theseconditions are true:

-   -   The pending tasks assigned to the worker or listener exceed its        task capacity.    -   The worker or listener session is the scheduler. (The scheduler        assigns tasks to its own worker or listener only when all other        workers or listeners are busy.)

Task Capacity

Task capacity is the maximum number of tasks that a worker or listenercan accept When the number of accepted tasks reaches this maximum, theworker or listener cannot accept additional tasks until it completes oneor more of them.

When the scheduler receives a task, it assigns the task to the worker orlistener with the greatest worker or listener weight-unless the pendingtasks assigned to that worker or listener exceed its task capacity. Whenthe preferred worker or listener has too many tasks, the schedulerassigns the new inbound task to the worker or listener with the nextgreatest worker or listener weight.

Enabling a session as a queue member tacitly sets its worker or listenertask capacity to 1. Programmers can tune task capacity based on twofactors:

-   -   Multi-tasking program on multiprocessing hardware.    -   On a multiprocessing computer, a multi-threaded program that        devotes n threads and n processors to inbound tasks has task        capacity n.    -   Communication time lag.    -   In most distributed queue applications, the communication time        is an insignificant fraction of the task turnaround time. That        is, the time required to assign a task and signal its completion        is very small compared to the time required to process the task        itself. For example, when average task turnaround time is 2000        milliseconds, of which communication time contributes only 10        milliseconds to the total, then task capacity is the same as the        number of processors or ads.

However, in some situations communication time can be significant—forexample, when the queue members are distributed at distant sitesconnected by a WAN. When communication time is significant, the meaningof task capacity changes; instead of signifying the number of tasks thata listener can process concurrently, it signifies the number of tasksthat can fill the listener's capacity despite the communication timelag. For example, when the average task turnaround time is 1500milliseconds, of which the average task processing time contributes 1000milliseconds to the total, then setting the task capacity to 3 minimizesthe listener's idle time between tasks.

When tuning task capacity to compensate for communication time lag,balance is critical. Underloading a listener (by setting its taskscapacity too low) can cause the listener to remain idle while it waitsfor the schedule to assign its next task. Conversely, overloading alistener (by setting its task capacity too high) can cause some assignedtasks to wait, while other listeners that might have accepted thosetasks remain idle.

Task Scheduling

In a further application of this invention, the broad concepts ofdistributed queuing can be applied to scheduling tasks for differenttask doing applications. In this application an application can beeither a scheduler or a worker or both. Each worker is assigned a weightindicating its ability to do work, usually the number of tasks it can dosimultaneously. Typically, workers assign their own weights.

One application/member of a group becomes the scheduler. Once thisoccurs, all other applications become designated workers only. Thescheduler becomes both a worker and the scheduler.

When a task is received by the group (the scheduler) it assigns the taskto the worker with the highest “weight” or ability to do tasks. Theworker then calls back to the scheduler accepting the task and, uponcompletion, returns a call to the scheduler indicating this fact. Incertain instances, the call back to the scheduler includes both anacceptance and a notification of task completion.

Two Appendices, A and B are attached. These appendices include detailedC coding information respectively for Certified messaging and formessage queuing.

All publications and patent applications mentioned in this specificationare herein incorporated by reference to the same extent as if eachindividual publication or patent application was specifically andindividually indicated to be incorporated by reference.

The invention now being filly described, it will be apparent to one ofordinary skill in the art that many changes and modifications can bemade thereto without departing from its spirit or scope.

Appendix A: Certified Message Delivery (Programming Details for CProgrammers)

As indicated previously, even though some communications are highlyreliable, certain applications require even stronger assurances ofdelivery. Certified delivery features offers greater certainty ofdelivery even in situations where processes and their networkconnections are unstable.

This Appendix A provides programming details for C programmers wishingto implement Certified message Delivery. The Appendix provides, in TableA1, an overview listing of Certified's messaging Deliver Datatypes andFunctions. Each Datatype or Function is then described in greater detailwith Cross-references to related Datatypes or Functions.

Certified Message Delivery CAPI

The following table summarizes the datatypes and functions in thecertified message delivery C API. TABLE A1 Certified Message Delivery:Datatypes and Functions Item Description rvcm_Enable ( ) Enable anexisting session for delivery tracking. rvcm_ListenSubject ( ) Listenfor broadcast messages, and request certified delivery wheneveravailable. rvcm_ListenInbox ( ) Open a delivery-tracking inbox to listenfor point-to-point messages, and request certified delivery wheneveravailable. rvcm_Callback Function type of callback functions thatreceive and process inbound messages for delivery-tracking listeners.rvcm_ListenId Certified listening calls return identifiers of this type.rvcm_seq Certified messages bear sequence numbers of this type.rvcm_close ( ) Close a delivery-tracking endpoint; stop listening formessages on it. rvcm_Send ( ) Send a labeled message, and track deliveryto cooperating listeners. rvcm_SendWithReply ( ) Send a labeled requestmessage, and track delivery to cooperating listeners. rvcm_AddListener () Pre-register an anticipated listener. rvcm_RemoveListener( ) Cancelcertified delivery of a subject to a listening correspondent.rvcm_DisallowListener( ) Cancel certified delivery of all subjects to alistening correspondent, and deny subsequent registration requests.rvcm_AllowListener( ) Invite a receiver to reinstate certified deliveryfor its listeners. rvcm_NoAutoConfirm( ) Override automatic confirmationof delivery. rvcm_confirm( ) Confirm delivery of a certified message.rvcm_ReviewLedger( ) Summarize the delivery status of messages in theledger, rvcm_ReviewCallback Function type of callback functions thatprocess ledger information for rvcm_ReviewLedger( ).rvcm_SyncLedgerFile( ) Synchronize the ledger file. rvcm_Error Datatype.Enumerates error codes for the certified message delivery API.rvcm_ErrorText( ) Return a text string describing an error code.

rvcm_Enable( ) Function Declaration rvcm_Error rvcm_Enable (  rv_Session session,   rv_Name name,   rv_Name reserved,   char*ledgerFile,   rv_Boolean requireOldMsgs

Purpose

Enable an existing session for delivery tracking.

Remarks

All other rvcm functions require an enabled session as an argument.Programs must call rvcm_Enable ( ) before any other calls related tocertified delivery.

A user can use an enabled session for both certified and non-certifiedcommunications. For example, an enabled session supports calls torvcm_Send ( ) and rv_Send ( ).

Once a session is enabled for certified delivery, it remains enableduntil terminated with rv_Term ( ). The user cannot subsequently changethe certified delivery parameters of the session.

Name

rvcm_Enable ( ) promotes its session argument to a delivery-trackingsession.

If name is NULL, then rvcm_Enable ( ) generates a unique, non-reusablename for this session.

If name is non-NULL, then the session binds that name. A correspondentcan persist beyond session termination only when it has both a reusablename and a file-based ledger.

Ledger File

Every delivery-tracking session stores the state of its certifiedcommunications in a ledger, which is stored in memory associated withthe process.

If ledgerFile is NULL, then this session uses a only process-basedledger. When the session or process terminates, all information in theledger is lost.

If ledgerFile specifies a valid file name, then this session uses thatfile for ledger storage. If the session or process terminates withincomplete certified communications, the ledger file records that state.When a new session binds the same reusable name, it reads the ledgerfile and continues certified communications from the state stored in thefile.

Even though a session uses a ledger file, it may sometimes replicateparts of the ledger in process-based storage for efficiency: however,programmers cannot rely on this replication.

If the operating system supports raw storage devices (also called rawpartitions), the user can specify such a device as the ledger file.

An optional prefix determines whether writing to the ledger file is asynchronous operation:

-   -   To specify synchronous writing (the default), either supply an        ordinary file name, or prepend the string sync* to the file        name; for example, “myLedger” (implicit) or        “sync*/local/myLedger” (explicit). Each time a ledger item is        written, the call does not return until the data is safely        stored in the file system.    -   To specify asynchronous writing, prepend the string nosync* to        the file name; for example, “nosync*/local/myLedger”. The ledger        file might not accurately reflect program state in cases of        hardware or operating system kernel failure.        -   A program that uses an asynchronous ledger file can            explicitly synchronize it by        -   calling rvcm_SyncLedgerFile( ), described below.

Parameters Parameter Description session Enable this session forcertified delivery tracking. name Bind this reusable name to thesession, so the session represents a persistent correspondent with thisname. If non-Null, the name must conform to the syntax rules for subjectnames. It cannot begin with reserved tokens. It cannot be a non-reusablename generated by another call to rvcm_Enable( ). If this argument isNULL, then rvcm_Enable( ) generates a unique, non- reusable name for theduration of the session. reserved This parameter is reserved for futureenhancement. The user must supply NULL for foilNard compatibility.ledgerFile If this argument is non-NULL, then this session uses afile-based ledger. The argument must represent a valid file name. Actuallocations corresponding to relative file names conform to operatingsystem conventions. Prepending nosync* to the file name specifiesasynchronous output to the file system. sync* or no prefix specifiessynchronous output (flushed before each output call returns). If thisargument is NULL, then this session uses a process-based ledger.requireOldMsgs This parameter indicates whether a persistentcorrespondent requires delivery of messages sent to a previous sessionwith the same name, for which delivery was not confirmed. Its valueaffects the behavior of other delivery-tracking senders. If thisparameter is RV_TRUE and name is non-NULL, then this session requirescertified senders to retain unacknowledged messages sent to thispersistent correspondent. When this session begins listening to theappropriate subjects, the senders can complete delivery. (It is an errorto supply RV_TRUE when name is NULL.) If this parameter is RV_FkLSr.,then this session does not require certified senders to retainunacknowledged messages. Certified senders may delete those messagesfrom their ledgers.

RVCM Error Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_SESSION_NAME The functionreceived an ill-formed reusable name. RVCM_ERR_NO_MEMORY The functioncould not complete because the operating system denied its request toallocate storage. RVCM_ERR_FILE_IO_ERROR rvcm_Enable ( ) encountered anerror while opening the ledger file. For example, an explicitly nameddirectory does not exist. RVCM_ERR_FILE_NO_PERMISSION File privilegesare insufficient for rvcm_Enable ( ) to open the ledger file.RVCM_ERR_LEDGER_NAME_CONFLICT rvcm_Enable ( ) received NULL as the nameparameter, but a nOn-NULL value as the ledgerFile parameter.RVCM_ERR_PARAMETER_CONFLICT The function received conflicting values forparameters. rvcm_Enable ( ) received RV_FALSE as its requireOldMsgsparameter, and NULL as its name parameter. A non-reusable name implies atransient correspondent, which cannot have backlog messages.RVCM_ERR_FILE_NOT_LEDGER_OWNER The reusable name recorded in the filediffers from the name of this session. rvcm_Enable ( ) stopped readingthe file. RVCM_ERR_CORRUPT_LEDGER_FILE The ledger file is corrupt.rvcm_Enable ( ) could read only part of the ledger file intoprocess-based memory. Some information may be lost.RVCM_ERR_SESSION_ALREADY_ENABLED rvcm_Enable ( ) received a session thatis already enabled for delivery tracking. It is illegal co enable asession more than once.

Coding Example

cm_err = rvcm_Enable(sess, “CM_EXAMPLE”. NULL,       “my_ledger_file”,RV_TRUE); if (cm_err != RVCM_OK)   {   fprintf(stderr, ‘Can't enable CMsession--%s\n’,     rvcm_ErrorText (sess, cm_err) );   exit (−1);   }See Also rvcm_SyncLedgerFile( ), below rvcm_ListenSubject( ) FunctionDeclaration rvcm_Error rvcm_ListenSubject (   rv_Session session,  rvcm_LisCenId* listenid,   rv_Name subject,   rvcm_CallbackdataCallbackFn,   rv_Opaque closureArg )

Purpose

Begin listening for messages that match the subject, and requestcertified delivery whenever available. Whenever a message arrives, thecallback function receives it.

Remarks

This function is parallel to rv_ListenSubject ( )—it creates an endpointto receive messages with matching subjects. The endpoint receives bothlabeled messages and ordinary messages.

When a labeled message arrives from an unfamiliar delivery-trackingsession, the receiving session requests certified delivery for thesubject. If the sending session accepts the request, then the twosessions cooperate to certify delivery of subsequent messages with thissubject.

Unlike ordinary listening endpoints, the user cannot maintain more thanone delivery-tracking listening endpoint per subject. When one endpointis already open, subsequent calls to rvcm_ListenSubject( ) with the samesubject return an error. (This restriction applies to eachdelivery-tracking session; however, a program with severaldelivery-tracking sessions can open independent delivery-trackinglisteners with identical subjects.)

Unlike rv_ListenSubject( ), the user cannot use rvcm_ListenSubject( ) tolisten to wildcard subjects.

The software automatically confirms message delivery when the datacallback function returns.

Parameters Parameter Description session A delivery-tracking session.listenId When rvcrn_ListenSubject( ) returns (without error), thislocation contains a handle denoting the new endpoint. To stop listeningon the subject, pass this handle to rvcm_Close( ). subject Listen formessages with this subject name. Wildcard subjects are illegal.dataCallbackFn When a message arrives, pass it to this callbackfunction. closureArg Pass this closure argument to the callbackfunction. This argument must be a pointer, but it can point to any typeof data. It contains any information needed by the callback function.This argument is treated as an opaque closure, forwarding it to thecallback function without accessing its value.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSI0N The function received a sessionargument that is not a valid rv_session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_ARG The function received anillegal argument. rvcm_ListenSubject( ) received either a NULL callbackfunction, or a NULL listenid pointer. RVCM_ERR_NO_MEMORY The functioncould not complete because the operating system denied its request toallocate storage. RVCM_ERR_BAD_SUBJECT rvcm_ListenSubject( ) received anill-formed subject name. Either it is NULL, or contained too many totalcharacters, too many characters in an element, too many elements, awildcard character, or an illegal prefix. RVCM_ERR_DUPLICATE_SUBJECTrvcm_ListenSubject( ) Can maintain at most one open listening endpointper subject (per session); it cannot open a second listening endpointfor this subject. RVCM_ERR_SESSION_NOT_ENABLED The function received asession that is not enabled for delivery tracking.

Coding Example

cm_err = rvcm_ListenSubject(sess, &listenId, subject,        CM_callback, myClosure);   if (cm_err != RVCM_OK)    fprintf(stderr, “error %s listening to \“%s\”\n”,      rvcm_ErrorText (sess, cm_err), subject); See Also rvcm_Callback;rvcm_ListenId; rvcm_ListenInbox( ); rvcm_Close( ), all described belowrvcm_ListenInbox( ) Function rvcm_Error rvcm_ListenInbox (   rv_Sessionsession,   rvcm_ListenId* listenid,   rv_Name inbox,   rv_SizeinboxLimit,   rvcm_Callback dataCallbackFn,   rv_Opaque closureArg)

Purpose

Open an inbox and begin listening for point-to-point messages addressedto it. Request certified delivery whenever available. Whenever a messagearrives, pass it to the callback function.

Remarks

This function is parallel to rv_ListenInbox ( )—it creates an inbox toreceive point-to-point messages. The inbox receives both labeledmessages and ordinary messages.

When a labeled message arrives from an unfamiliar delivery-trackingsession, the receiving session requests certified delivery for the inboxname. If the sending session accepts the request, then the two sessionscooperate to certify delivery of subsequent messages to this inbox.

Certified delivery to an inbox is limited to the duration of the inbox.Once the users closes an inbox or terminates its session, the inbox andits name become obsolete; the user can never open another inbox with thesame name. Since the system can never complete delivery of messagesaddressed to an obsolete inbox, it automatically deletes stored messageswhen it detects that an inbox has become obsolete.

The system automatically confirms message delivery when the datacallback function returns.

Parameters Parameter Description session A delivery-tracking session.listenId When rvcm_ListenInbox ( ) returns (without error), thislocation contains a handle denoting the new inbox. To stop listening,pass this handle to rvcm_Close ( ). inbox Location to store thegenerated name of the new inbox. The allocated space must be at leastRV_t, mX_INBOX_NAME (currently 100 bytes). inboxLimit Number of bytesallocated to store the new inbox name. dataCallbackFn When a messagearrives, pass it to this callback function. closureArg Pass this closureargument to the callback function. This argument must be a pointer, butit can point to any type of data. It contains any information needed bythe callback function, the system treats this argument as an opaqueclosure, forwarding it to the callback function without accessing itsvalue.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_ARG The function received anillegal argument. rvcm_ListenInbox ( ) received either a NULL inbox namepointer, a NULL callback function, or a NULL listenid pointer.RVCM_ERR_NO_MEMORY The function could not complete because the operatingsystem denied its request to allocate storage.RVCM_ERR_SESSION_NOT_ENABLED The function received a session that is notenabled for delivery tracking.

Coding Example

char inboxName [RV_MAX_INBOX_NAME]; cm_err = rvcm_ListenInbox(sess,&listenId, inboxName,         sizeof(inboxName), CM_callback,myClosure);   if (cm_err != RVCM_OK)     fprintf(stderr, “error %slistening to certified inbox.\n”,       rvcm_ErrorText(sess, cm_err));See Also, rvcm_Callback, below rvcm_ListenId, below rvcm_ListenSubject(), above rvcm_Close( ), below. rvcm_Callback Datatype Declaration void*rvcm_Callback (   rv_Session session,   rv_Name subject,   rv_NamereplyName   rvmsg_Type msgType,   rvmsg_Size msgSize,   rvmsgData msg,  rvcm_Seq sequenceNum,   rv_Name senderName,   rv_Opaque closureArg )

Purpose

rvem_Callback is the function type of data callback functions todelivery-tracking listeners. Applications define functions of this typeto receive inbound messages and take appropriate actions.

Remarks

This function type is parallel to rv_Callback. Notice that its functionsignature includes two additional parameters, senderName andsequenceNum, to receive the tracking data that labels the inboundmessage. Application programs can use these arguments for testing andauditing.

The system automatically confirms message delivery when the datacallback function returns.

The user can write several callback functions to process the variouskinds of messages that the application expects to receive. The user canuse the same callback function to process messages at several endpoints.Callback functions can take any action in processing a message, exceptfor the following restrictions:

-   -   Callback functions must not attempt to modify the data (the        values of the parameters msg, subject, reillyName and        senderName) in any manner. The callback function receives data        through pointers; the actual data resides in memory that does        not belong to the application. The data pointers remain valid        only until the callback function returns.    -   The data callback functions must return promptly.

Parameters Parameter Description session This parameter receives thecurrent session. subject This parameter receives the destination subjectname of the inbound message. Do not modify this value. This pointerremains valid only until the callback function returns. replyName If theinbound message carries a name for replies, this parameter receives it.Otherwise NULL. Do not modify this value. This pointer remains validonly until the callback function returns. msgType This parameterreceives the datatype of the message. msgSize This parameter receivesthe size (in bytes) of the message. msg This parameter receives apointer to the message data. Do not modify this value. This pointerremains valid only until the callback function returns. sequenceNum Ifthe message is certified, this parameter receives the sequence numberthat the sender assigned to the message. Otherwise, this parameterreceives zero. senderName If the message is labeled, this parameterreceives the name of the delivery-tracking session that sent themessage. Otherwise, this parameter receives NULL. Do not modify thisvalue. This pointer remains valid only until the callback functionreturns. closureArg This parameter receives a closure argument suppliedby the application when it began listening. This argument is a pointer,but it can point to any type of data. It contains any information neededby the callback function, the system treats this argument as an opaqueclosure, forwarding it to the callback function without accessing itsvalue.

Coding Example

This example code illustrates a data callback function for receivingmessages with certified delivery. void CM-callback (     rv_Sessionsession,     rv_Name subject,     rv_Name replyName,     rvmsg_TypemsgType,     rvmsg_Size msgSize,     rvmsg_Data msg,     rvcm_SeqseqNumber,     rv_Name sender,     rv_Opaque myClosureArg ) {  printf(“Received: subject=%s, reply=%s. message=”,     subject,(replyName!=NULL ? replyName : “<none>”));   rvmsg_PrintItem(session,msgType. msgSize, msg, NULL);   printf(“\n”);   printf(“ sequencenumber=%ld. sender=%s\n”,     seqNumber, (sender!=NULL ? sender :“<none>”));   fflush(stderr); } See Also rvcm_ListenId; rvcm_Seq; andrvcm_Close( ), below. rvcm_Listenld Datatype Declaration typedef void*rvcm_ListenId;

Purpose

The rvcm_ListenSubject ( ) arid rvcm_ListenInbox ( ) functions return ahandle of type rvcm_ListenId. To stop listening for the correspondinginformation, pass this handle to rvcm_Close ( ).

Remarks

an rvcm_ListenId is not meaningful outside of the session in which itwas created. Each rvcm_ListenId is a unique handle representing anassociation between a subject and a callback function. Use rvcm_ListenIdonly within the local program that receives it from one of the listeningfunctions, and treat it as opaque.

rvcm_Seq

Datatype

Declaration

typedef unsigned long rvcm_Seq;

Purpose

Sequence number of a labeled message.

Remarks

Sequence numbers are limited to 32 bits on all platforms (even platformsthat support 64-bit integers). rvcm_Close( ) Function Declarationrvcm_Error rvcm_Close (   rv_Session   session,   rvcm_ListenIdlistenid

Purpose

Close a delivery-tracking endpoint; stop listening for messages on it.

Remarks

This function is parallel to rv_Close ( ).

Cooperating senders receive a REGISTRATION. CLOSED advisory, indicatingthat the delivery tracking agreement is no longer in effect. Sendersreceive a DELIVERY. FAILED advisory for each undelivered message to theclosed endpoint, and the system removes undelivered messages from thesender's ledger.

The system deletes the listener's ledger items corresponding to theclosed subject.

When rvcm_Close ( ) closes an endpoint, it generates a HOST.LISTEN.STOPadvisory message to inform other applications that this application hasstopped listening to the subject.

It is important that a persistent listener close a delivery-trackingendpoint when it no longer requires certified delivery of thecorresponding subject-and only then. Open endpoints cause certifiedsenders to store messages in the ledger while awaiting deliveryconfirmation from the sender. From the sender's perspective, apersistent listener that exits without closing its listening endpointsappears the same as a listener that terminates abnormally; the sendercontinues to store messages awaiting the return of the Listener process.Once an endpoint is closed, senders do not store certified messages forthat listener, and successive listener processes with the samecorrespondent name do not receive certified delivery of messages sent inthe interim.

Coding Example

Close endpoints when the application is finished receiving data Closingendpoints lets TiB/Rendezvous software re-use the associated storageresources. After closing an endpoint, delete all references to it, toguard against closing it twice.

It is illegal to close the same endpoint more than once. On someplatforms, the error RVCM_ERR_NONEXISTENT_ID results; on otherplatforms, the result can be a fatal error

(because it references dynamically allocated memory that has beenfreed).

This code fragment illustrates the recommended idiom for closingendpoints: if (foo->listenId != NULL)   (rvclm_Close(foo->listenId);  foo->listenId = NULL; }

Parameters Parameter Description session The delivery-tracking sessionthat created the endpoint. listenId Close the endpoint that this handledenotes.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_Session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_ARG The function received anillegal argument. rvcm_Close( ) received a NULL listenId pointer.RVCM_ERR_NONEXISTENT_ID rvcm_Close ( ) received a NULL listenId pointereither it is NULL, or it points to something other than anrvcm_ListenId, or it points to an endpoint that has already been closed.RVCM_ERR_NO_MEMORY The function could not complete because the operatingsystem denied its request to allocate storage.RVCM_ERR_SESSION_NOT_ENABLED The function received a session that is notenabled for delivery tracking.

See Also rvcm_ListenId, above. rvcm_Send( ) Function Declarationrvcm_Error rvcm_Send (   rv_Session session,   rv_Name subject,  rvmsg_Type msgType,   rvmsg_Size msgSize,   rvmsg_Data msg,   unsignedlong timeLimit,   rvcm_Seq* sequenceNum )

Purpose

Send a labeled message, and track delivery to cooperating listeners.

Remarks

This function is parallel to rv_Send ( ). Notice that its signatureincludes two additional parameters, timeLimit and SequenceNum.

Use timeLimit to specify the duration of the message (in seconds). Thesystem retains the message in its ledger until either it receivesdelivery confirmation from all cooperating listeners, or the timeLimitexpires. If the time limit expires before delivery is complete, thesystem removes the message from the ledger, and generates a DELIVERY.FAILED advisory message listing the cooperating listeners that did notconfirm delivery of the message.

We recommend a timeLimit value greater than 60 seconds, since the domainholds messages for 60 seconds.

rvcm_Send ( ) labels the message with the name of the delivery-trackingsession and a sequence number. rvcm_Send ( ) passes the sequence numberback to the caller in its sequenceNum parameter (the user can use thisnumber for auditing).

Each sending session maintains a separate sequence for each subject itsends. As a result, receivers can uniquely identify each labeled messageby the three data callback arguments subject, senderName andsequenceNum.

When msg has self-evident length, the user may supply zero for msgSize(the system computes the actual size automatically). Types withself-evident size are RVMSG_RVMSG, RVMSG_STRING (when the string isNULL-terminated) and RVMSG_ENCRYPTED. All other types require anexplicit size argument in this call.

rvcm_Send( )

rvcm_Send ( ) copies its arguments. After rvcm_Send ( ) returns, theuser may free or reuse the storage (for example, a message buffer).

Warning

It is illegal to send messages to wildcard subject names. Althoughrvcm_Send ( ) does not prevent the user from sending illegally towildcard subjects, the results are unpredictable.

Parameters Parameter Description session A delivery-tracking session.subject Send the message to this subject name or inbox. msgType Datatypeof the message data. msgSize Length of the data (in bytes). msg Locationof the data to send. timeLimit Retain the message in the ledger, andcontinue attempts at delivery either until completion of delivery oruntil this time limit (in seconds) expires. Zero is a special value,indicating no time limit; the message remains in the ledger untildelivery is complete to all certified listeners. A non-zero value lessthan 60 seconds adds no advantage over ordinary reliable messagedelivery, since rvd retains and retransmits messages for 60 seconds.sequenceNum This location receives the sequence number of this message.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_Session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_ARG The function received anillegal argument. rvcm_Send ( ) or rvcm_SendWithReply ( ) receivedeither a NULL subject, or a NULL sequence number pointerRVCM_ERR_NO_MEMORY The function could not complete because the operatingsystem denied its request to allocate storage. RVCM_ERR_BAD_SUBJECTrvcm_Send ( ) or rvcm_SendWithReply ( ) received an ill-formed subjectname. Either it contained too many total characters, too many charactersin an element, or too many elements. RVCM_ERR_SESSION_NOT_ENABLED Thefunction received a session that is not enabled for delivery tracking.

Coding Example

int time_limit = 600; /* 600sec = 10min */ cm_err = rvcm_Send(sess,subject, type, sizeof(msg), msg,     time_limit, &seq_no); if (cm_err ==RVCM_OK)   fprintf(stderr, “Sent sequence num %d\n”.seq_no); else  fprintf(stderr, “Error while sending certified message: %s\n”.    rvcm_ErrorText (sess, cm_err) ); See Also rvcm_Seq, abovervcm_SendWithReply( ), below. rvcm_SendWithReply( ) Function Declarationrvcm_Error rvcm_SendWithReply (   rv_Session session,   rv_Name subject,  rv_Name replyName,   rvms g_Type msgType,   rvmsg_Size msgSize,  rvmsg_Data msg,   unsigned long timeLimit,   rvcm_Seq* sequenceNum

Purpose

Send a labeled request message, and track delivery to cooperatinglisteners. A request message includes a reply name as a return addressfor response messages.

Remarks

This function is parallel to rv_SendWithReply ( ). Notice that itssignature includes two additional parameters, timeLimit and sequcnceNum.

The reply name must be the subject name of an open listening endpoint(either broadcast or inbox). An application may receive zero, one orseveral responses to a request message. Before the user callsrvcm_SendWithReply ( ) the user must ensure that the appropriateapplication components arc listening to the reply name.

rvcm_SendWithReply ( ) is a non-blocking function. It returnsimmediately, and the callback function receives any repliesasynchronously. A reply is not guaranteed (for example, if the receiverdoes not send any reply).

Use timeLimit to specify the duration of the message, the system retainsthe message in its ledger until either it receives delivery confirmationfrom all cooperating listeners, or the timeLimit expires. If the timelimit expires before delivery is complete, the system removes themessage from the ledger, and generates a DELIVERY.FAILED advisorymessage listing the cooperating listeners that did not confirm deliveryof the message.

A timeLimit value greater than 60 seconds is recommended, since thedomain holds messages for 60 seconds.

rvcrn_Send WithReply( )

rvcm_SendWithReply( ) labels the message with the name of thedelivery-tracking session and a sequence number. rvcm_SendWithReply( )passes the sequence number back to the caller in its sequenceNumparameter (the user can use this number for auditing).

Each sending session maintains a separate sequence for each subject itsends. As a result, receivers can uniquely identify each labeled messageby the three data callback arguments subject, senderName andsequenceNum.

When msg has self-evident length, the user may supply zero for msgSize(the system computes the actual size automatically). Types withself-evident size are RVMSG_RVMSG, RVMSG_STRING (when the string isNULL-terminated) and RVMSG_ENNCRYPTED. All other types require anexplicit size argument in this call.

rvcm_SendWithReply( ) copies its arguments. After rvcm_SendWithReply( )returns, the user may free or reuse the storage (for example, a messagebuffer).

Warning

It is illegal to send messages to wildcard subject names. Although thefunction rvcm_SendWithReply( ) does not prevent the user from sendingillegally to wildcard subjects, the results are unpredictable.

Parameters Parameter Description Session A delivery-tracking session.Subject Send the message to this subject name or inbox. ReplyNameSubject name for replies to this request message (similar to a returnaddress on a letter, and delivered to receiving applications in thereplyName argument of the callback function). The reply name may be aninbox or subject name. Before calling rvcm_SendWithReply( ), ensure thata listening endpoint is already open for the reply name. MsgTypeDatatype of the message data. MsgSize Length of the data (in bytes). MsgLocation of the data to send. timeLimit Retain the message in theledger, and continue attempts at delivery either until completion ofdelivery or until this time limit (in seconds) expires. Zero is aspecial value, indicating no time limit; the message remains in theledger until delivery is complete to all certified listeners. A non-zerovalue less than 60 seconds adds no advantage over ordinary reliablemessage delivery, since rvd retains and retransmits messages for 60seconds. sequenceNum This location receives the sequence number of thismessage.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_Session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_ARG The function received anillegal argument. rvcm_Send( ) or rvcm_SendWithReply( ) received eithera NULL subject, or a NULL sequence number pointer. RVCM_ERR_NO_MEMORYThe function could not complete because the operating system denied itsrequest to allocate storage. RVCM_ERR_BAD_SUBJECT rvcm_Send( ) orrvcm_SendWithReply( ) received an ill-formed subject name. Either itcontained too many total characters, too many characters in an element,or too many elements. RVCM_ERR_SESSION_NOT_ENABLED The function receiveda session that is not enabled for delivery tracking.

Coding Example

cm_err = rvcm_SendWithReply(sess, subject, reply,       type,sizeof(msg}, msg,       600. &seq_no); (cm_err == RVCM_OK)  fprintf(stderr, “Sent sequence num %d\n”, seq_no); else  fprintf(stderr, “Error while sending certified message: %s\n”,    rvcm_ErrorText (sess, cm_err) ); See Also rvcm_Seq, page 203; andrvcm_SendWithReply( ), above. rvcm_Add Listener( ) Function Declarationrvcm_Error rvcm_AddListener (   rv_Session session,   rv_Name name,  rv_Name subject )

Purpose

Pre-register an anticipated listener.

Remarks

Some sending applications can anticipate requests for certifieddelivery-even before the listening applications begin running. In suchsituations, the sender can pre-register listeners so the system beginsstoring outbound messages in the sender's ledger, when the listenerrequests certified delivery, it receives the backlogged messages.

If the correspondent with this name already receives certified deliveryof this subject from this sender session, then rvcm_AddListener( ) hasno effect.

If the correspondent with this name is disallowed, thenrvcm_AddListener( ) returns an error. The usercan callrvcm_AllowListener( ) to supersede the effect of a prior call torvcm_DisallowListener( ); then call rvcm_AddListener( ) again

Parameters Parameter Description session A delivery-tracking session.subject Anticipate a listener for this subject. name Anticipate alistener from a correspondent with this reusable name.rvcm_AddListener( )

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_session (for example. NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_SESSION_NAME The functionreceived an ill-formed reusable name. RVMC_ERR_BAD_ARG The functionreceived an illegal argument. rvcm_AddListener( ) received a NULLlistener name. RVCM_ERR_SESSION_NOT_ENABLED The function received asession that is not enabled for delivery tracking. RVCM_ERR_BAD_SUBJECTThe function received an ill-formed subject name. Either it is NULL, orcontained too many total characters, too many characters in an element,too many elements, or an illegal prefix. RVCM_ERR_DISALLOWED_LISTENERrvcm_AddListener( ) cannot add this listener because it is disallowed.First call rvcm_AllowListener( ).

Coding Example

cm_err = rvcm_AddListener(sess, “LISTENER_17”. subject); if(cm_err !=RVCM_OK)   {   fprintf(stderr, “Can't add CM listener:\n %s\n”,    rvcm_ErrorText(sess, cm_err));   exit(−1);   } See Alsorvcm_RemoveListener( ), below. rvcm_RemoveListener( ) FunctionDeclaration rvcm_Error rvcm_RemoveListener (   rv_Session session,  rv_Name name, /* listening correspondent name */   rv_Name subject )

Purpose

Unregister a specific listener at a specific correspondent, and freeassociated storage in the sender's ledger.

Remarks

This function cancels certified delivery of the specific subject to thecorrespondent with this name. The listening correspondent maysubsequently re-register for certified delivery of the subject. (Incontrast, rvcm_DisallowListener( ) cancels certified delivery of allsubjects to the correspondent and prohibits re-registration.)

Senders usually call this function when the ledger item for a listeningcorrespondent has grown very large. Such growth indicates that thelistener is not confirming delivery, and may have terminated. Removingthe listener reduces the ledger size by deleting messages stored for thelistener.

When a sending program calls this function, certified delivery softwarein the sender behaves as if the listener had closed the endpoint for thesubject. The sending program deletes from its ledger all informationabout delivery of the subject to the correspondent with this name. Thesending program receives a REGISTRATION. CLOSED advisory, to trigger anyoperations in the callback function for the advisory.

If the listening correspondent is available (running and reachable), itreceives a REGISTRATION.NOT_CERTIFIED advisory, informing it that thesender no longer certifies delivery of the subject.

If the correspondent with this name does not receive certified deliveryof the subject from this sender session, then rvcm_RemoveListener( )returns RVCM_ERR_BAD_SUBJECT.

Parameters Parameter Description session A delivery-tracking session.subject Cancel certified delivery of this subject. name Cancel certifieddelivery of the subject to the correspondent with this name.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_Session (for example, NULL Or a sessionthat has already terminated). RVCM_ERR_BAD_ARG The function received anillegal argument. rvcm_RemoveListener( ) received a NULL listener nameor NULL subject; or the sender does not certify delivery of the subjectto the listener. RVCM_ERR_SESSION_NOT_ENABLED The function received asession that is not enabled for delivery tracking. RVCM_ERR_BAD_SUBJECTThe function received an ill- formed subject name. Either it is NULL, orcontained too many total characters, too many characters in an element,too many elements, or an illegal prefix. rvcm_RemoveListener( ) receiveda subject containing wildcard characters; or the sender has not sentcertified messages on this subject. RVCM_ERR_DISALLOWED_LISTENERrvcm_RemoveListener( ) cannot cancel certified delivery to this listenerbecause the listener is disallowed.

Coding Example

cm_err = rvcm_RemoveListener(sess, listener, subject); if(cm_err !=RVCM_OK)   {   fprintf(stderr, “Can't remove CM listener:\n %s\n”,    rvcm_ErrorText(sess, cm_err));   exit(−1);   } See Alsorvcm_AddListener( ), above; and rvcm_DisallowListener( ), below.rvcm_DisallowListener( ) Function Declaration rvcm_Errorrvcm_DisallowListener (   rv_Session session,   rv_Name name )

Purpose

Cancel certified delivery to all listeners at a specific correspondent.Deny subsequent certified delivery registration requests from thoselisteners.

Remarks

Disallowed listeners still receive subsequent messages from this sender,but delivery is not certified. That is:

-   -   The listener receives a REGISTRATION.NOT_CERTIFIED advisory,        informing it that the sender has cancelled certified delivery of        all subjects.    -   If the sender's ledger contains messages sent to the disallowed        listener (for which this listener has not confirmed delivery),        then the system removes those ledger items, and does not attempt        to redeliver those messages.    -   The system presents subsequent messages (from the cancelling        sender) to the listener with sequence number zero, to indicate        that delivery is not certified.

Senders can promptly revoke the acceptance of certified delivery bycalling rvcm_DisallowListener( ) within the callback function thatprocesses the REGISTRATION.REQUEST advisory.

This function disallows a correspondent by name. If the correspondentterminates, and another process instance (with the same reusable name)takes its place, the new process is still disallowed by this sender.

To supersede the effect of rvcm_DisallowListener( ), callrvcm_AllowListener( ).

Parameter Parameter Description session A delivery-tracking session nameCancel certified delivery to listeners at the session with this name.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_Session (for example, NULL< or a sessionthat has already terminated). RVCM_ERR_BAD_SESSION_NAME The functionreceived an ill- formed reusable name. RVCM_ERR_BAD_ARG The functionreceived an illegal argument. rvcm_DisallowListener( ) received a NULLlistener name. RVCM_ERR_SESSION_NOT_ENABLED The function received asession that is not enabled for delivery tracking.

Coding Example

cm_err = rvcm_DisallowListener(sess, “LISTENER_17”); if(cm_err !=RVCM_OK)   {   fprintf(stderr, “Can't disallow CM listener:\n %s\n”,    rvcm_ErrorText(sess, cm_err));   exit(−1);   } rvcm_AllowListener( )Function Declaration rvcm_Error rvcm_AllowListener (   rv_Sessionsession,   rv_Name name )

Purpose

Invite the named receiver to reinstate certified delivery for itslisteners, superseding the effect of any previous calls torvcm_DisallowListener( ).

Remarks

Upon receiving the invitation to reinstate certified delivery, thesystem at the listening program automatically sends new registrationrequests. The sending program accepts these requests, restoringcertified delivery.

Parameters Parameter Description session A delivery-tracking session.name Accept requests for certified delivery to listeners at the sessionwith this name.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_Session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_SESSION_NAME The functionreceived an ill- formed reusable name. RVCM_ERR_BAD_ARG The functionreceived an illegal argument. rvcm_AllowListener( ) received a NULLlistener name. RVCM_ERR_SESSION_NOT_ENABLED The function received asession that is not enabled for delivery tracking.

Coding Example

cm_err = rvcm_AllowListener(sess, “LISTENER_17”); if(cm_err != RVCM_OK)  {   fprintf(stderr, “Can't allow CM listener:In %sin”,    rvcm_ErrorText(sess, cm_err));   exit(−1);   } rvcm_NoAutoConfirm( )Function Declaration rvcm_NoAutoConfirm(   rv_Session session,  rvcm_ListenId listenid);

Purpose

Override automatic confirmation of delivery for this listening endpoint.

Remarks

The default behavior of certified listeners is to automatically confirmmessage delivery upon return from the data callback function (seervcm_Callback, above). This call selectively overrides this behavior forthis specific listening endpoint. (This call does not affect otherlistening endpoints.)

By overriding automatic confirmation, the listener assumesresponsibility for explicitly confirming each inbound certified messageby calling rvcm_Confirm( ).

Consider overriding automatic confirmation when processing inboundmessages involves asynchronous activity, such as computations in otherthreads, database queries, or additional network communications.

No method exists to restore the default behavior, reversing the effectof this function. Parameters

Parameter Parameter Description session A delivery-tracking session.listenId Override automatic confirmation for inbound certified messagesto this listening endpoint.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_Session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_NONEXISTENT_IDrvcm_NoAutoConfirm( ) received an unusable listenId pointer-either NULL,or it points to something other than an rvcm_ListenId, or it has alreadybeen closed.

See Also rvcm_Callback above, and rvcm_Confirm( ), below. rvcm_Confirm() Function Declaration rvcm_Confirm( )   rv_Session session,  rvcm_ListenId listenerId,   rv_Name senderName.   rvcm_SeqsequenceNumber)

Purpose

Confirm delivery of a certified message.

Remarks

Use this function only in programs that override automatic confirmation.

The triplet of subject name, sender and sequence number uniquelyidentifies each certified message. The subject name is already stored in-he listening endpoint. The other two components—sender and sequencenumber—are explicit parameters of this function.

Parameters Parameter Description session A delivery-tracking session.listenId Confirm delivery of a message by this listening endpoint.senderName Confirm delivery of a message from the sender with thiscorrespondent name. sequenceNumber Confirm delivery of the message withthis sequence number.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_Session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_ARG The function received anillegal argument. rvcm_Confirm( ) received a sequence number argumentthat is out of range. RVCM_ERR_ID_CONFIRM_CONFLICT rvcm_Confirm( )received a listenId that automatically confirms delivery. rvcm_Confirm() is only valid after overriding automatic confirmation withrvcm_NoAutoConfirm( ). RVCM_ERR_NONEXISTENT_ID rvcm_Confirm( ) receivedan unusable listenId pointer-either NULL, or it points to somethingother than an rvcm_ListenId, or it has already been closed.RVCM_ERR_NONEXISTENT_PUBLISHER rvcm_confirm( ) received a senderNameargument that is not recognized as the name of a certified sender.

See Also rvcm_Callback; and rvcm_NoAutoConfirm( ), above.rvcm_ReviewLedger( ) Function Declaration rvcm_Error rvcm_ReviewLedger  rv_Session session,   rv_Name subject,   rvcm_ReviewCallbackreviewCallbackFn   rv_Opaque closureArg );

Purpose

Summarize the delivery status of messages in the ledger,

Remarks

The callback function receives one message for each matching subjectstored in the ledger. For example, when rvcm_ReviewLedger( ) receivesFOO. * as its subject argument, it calls the callback functionseparately for these matching subjects—once for FOO.BAR, once forFOO.BAZ, and once for FOO.BOX.

However, if the callback function returns non-NULL, thenrvcm_ReviewLedger( ) returns immediately.

If the ledger does not contain any matching items, rvcm_ReviewLedger( )returns normally without calling the callback function.

For information about the Content and format of the callback messages,see rvcm_ReviewCallback, below.

Parameters Parameter Description session A delivery-tracking session.subject Review ledger items with this subject. If this subject containswildcard characters (“*” or “>”), then review all items with matchingsubject names. The callback function receives a separate message foreach matching subject in the ledger. reviewCallbackFn This functionreceives the review messages. closureArg Pass this closure argument tothe callback function. This argument must be a pointer, but it can pointto any type of data. It contains any information needed by the callbackfunction, the system treats this argument as an opaque closure,forwarding it to the callback function without accessing its value.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_Session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_ARG The function received anillegal argument. rvcm_ReviewLedger( ) received a NULL subject name or aNULL review callback function. RVCM_ERR_NO_MEMORY The function could notcomplete because the operating system denied its request to allocatestorage. RVCM_ERR_SESSION_NOT_ENABLED The function received a sessionthat is not enabled for delivery tracking.

Coding Example

fprintf(stdout,“\nLedger review for subject “%s”, %d:\n”,     subject,reviewMax); /*** See rvcm_ReviewCallback example function, below. ***/cm_err = rvcm_ReviewLedger (session, rv_Name)subject,          myReviewLedgerCallback,           (rv_Opaque)&reviewMax); if (cm_err != RVCM_OK)   {   fprintf(stderr, “Review ledger failed for“%s”:\n\t%s\n”,     subject, rvcm_ErrorText(sess. cm_err));   } See Alsorvcm_ReviewCallback, above. rvcm_ReviewCallback Datatype Declarationvoid* rvcm_ReviewCallback (   rv_Session session,   rv_Name subject,  rvmsg_Msg msg,   rv_Opaque closureArg )

Purpose

rvcm_ReviewCallback is the function type of callback functions forreviewing the ledger. Applications define functions of this type toprocess the summary messages from rvcm_ReviewLedger( ).

Remarks

rvcm_ReviewLedger( ) calls this callback once for each matching subjectin the ledger.

To continue reviewing the ledger, return NULL from this callbackfunction. To stop reviewing the ledger, return non-NULL from thiscallback function; rvcm_ReviewLedger( ) returns immediately. ParameterDescription session This parameter receives the current session. subjectThis parameter receives the subject name that the message summarizes.msg This parameter receives a summary message describing the deliverystatus of messages in the ledger. The table below describes the fieldsof the summary message. closureArg This parameter receives a closureargument, which the application supplied when it calledrvcm_ReviewLedger( ). This argument is a pointer, but it can point toany type of data. It contains any information needed by the callbackfunction. The system treats this argument as an opaque closure,forwarding it to the callback function without accessing its value.

Message Content Field Name Description subject The subject that thismessage summarizes. This field has datatype RVMSG_STRING.seqno_last_sent The sequence number of the most recent message sent withthis subject name. This field has datatype RVMSG_UTNT. total_msgs Thetotal number of messages with this subject name. This field has datatypeRVMSG_UINT. total_size The total storage (in bytes) occupied by allmessages with this subject name. If the ledger contains ten messageswith this subject name, then this field sums the storage space over allof them. This field has datatype RVMSG_UINT. listener Each summarymessage can contain one or more fields named listener. Each listenerfield contains a nested submessage with details about a singleregistered listener. This field has datatype RVMSG_RVMSG. listener.nameWithin each listener submessage, the name field contains the name of thedelivery- tracking listener. This field has datatype RVMSG_STRING.listener.last_confirmed Within each listener submessage, thelast_confirmed field contains the sequence number of the last messagefor which this listener confirmed delivery. This field has datatypeRVMSG_UINT.

Coding Example

/*** See rvcm_ReviewLedger( ) example call. above. ***/ void *myReviewLedgerCallback(rv_Session sess,     rv_Name subject,    rvmsg_Msg msg,     rv_Opaque arg) { int * count = (int*) arg; /*Print the ledger item. */ printf(“\nLedger item for ‘%s’:\n”, subject);rvmsg_Print(sess, msg, NULL); printf(“\n”); if ( *count ) {  (*count)−−; if (( *count ) > 0);  {  /* When count reaches zero, stop. Return from rvcm_ReviewLedger( ) */  return((void*)sess);  } } return(NULL); /*Otherwise, continue to the next item. */ See Also rvcm_ReviewCallbackrvcm_ReviewLedger( ), above. rvcm_SyncLedgerFile( ) Function Declarationrvcm_Error rvcm_SyncLedgerFile (rv_Session session);

Purpose

Synchronize the ledger file to its storage medium,

Remarks

When this function returns, the session's current state is safely storedin the ledger file.

Delivery-tracking sessions that use synchronous ledger files need notcall this function, since the current state is automatically written tothe file system before returning.

Parameters Parameter Description session Synchronize the ledger fileassociated with this delivery-tracking session.

Errors RVCM Error Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_Session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_SESSION_NOT_ENABLED The functionreceived a session that is not enabled for delivery tracking.RVCM_ERR_FILE_IO_ERROR rvcm_SyncLedgerFile( ) encountered an error whilewriting the ledger file.

See Also rvcm_Enable( ), above. rvcm_Error Datatype rvcm_Error iS artenumerated type for error codes. Table A2 lists the possible rvcm_Errorvalues. The user can use the function rvcm_ErrorText( ) to convertrvcm_Error message codes to descriptive text. For more information, seervcm_ErrorText( ) on page 244.

TABLE A2 Enumerated Values of rvcm_Error RVCM Error Code IndicatesRVCM_OK No error. The call completed successfully. RVCM_ERR_INIT_FAILURErvcm_EnableQueue( ) could not initialize either the certified deliveryor fault tolerance components upon which it depends.RVCM_ERR_INVALID_SESSION The function received a session argument thatis not a valid rv_Session (for example, NULL, or a session that hasalready terminated). RVCM_ERR_BAD_SESSION_NAME The function received anill-formed reusable name. rvcm_ListenSubject( ) received either a NULLcallback function, or a NULL listenid pointer. rvcm_ListenInbox( )received either a NULL inbox name pointer, a NULL callback function, ora NULL listenid pointer. rvcm_DisallowListener( ) received a NULLlistener name. rvcm_AllowListener( ) received a NULL Listener name.rvcm_AdclListener( ) received a NULL listener name. rvcm_RemoveListener() received a NULL listener name or NULL subject; or the sender does notcertify delivery of the subject to the listener. rvcm_Send( ) orrvcm_SendWithReply( ) received either a NULL subject, or a NULL sequencenumber pointer. rvcm_ReviewLedger( ) received a NULL subject name or aNULL review callback function. rvcm_Confirm( ) received a sequencenumber argument that is out of range. RVCM_ERR_NO_MEMORY The functioncould not complete because the operating system denied its request toallocate storage. RVCM_ERR_BAD_SUBJECT rvcm_Send( ). rvcm_SendWithReply() or rvcm_ListenSubject( ) received an ill- formed subject name. Eitherit is NULL, or contained too many total characters, too many charactersin an element, too many elements, a wildcard character, or an illegalprefix. rvcm_RemoveListener( ) received a subject containing wildcardcharacters; or the sender has not sent certified messages on thissubject. RVCM_ERR_ID_CONFIRM_CONFLICT rvcm_Confirm( ) received alistenid that automatically confirms delivery. rvcm_confirm( ) is onlyvalid after overriding automatic confirmation with rvcm_NoAutoConfirm(). RVCM_ERR_NONEXISTENT_ID rvcm_Close( ), rvcm_NoAutoConfirm ( ), orrvcm_Confirm( ) received an unusable listenid pointer--either NULL, orit points to something other than an rvcm_ListenId, or it has alreadybeen closed. RVCM_ERR_DUPLICATE_SUBJECT rvcm_ListenSubject( ) can openat most one listening endpoint per subject; it cannot open a secondlistening endpoint for this subject. RVCM_ERR_NONEXISTENT_PUBLISHERrvcm_Confirm( ) received a senderName argument that is not recognized asthe name of a certified sender. RVCM_ERR_DISALLOWED_LISTENERrvcm_AddListener( ) cannot add this listener because it is disallowed.First call rvcm_AllowListener( ). rvcm_RemoveListener( ) cannot cancelcertified delivery to this listener because the listener is disallowed.RVCM_ERR_SESSION_ALREADY_ENABLED rvcm_Enable( ) received a session thatis already enabled for delivery tracking. It is illegal to enable asession more than once. RVCM_ERR_SESSION_NOT_ENABLED The functionreceived a session that is not enabled for delivery tracking.RVCM_ERR_LEDGER_NAME_CONFLICT rvcm_Enable( ) received NULL as the nameparameter, but a non-NULL value as the ledgerFile parameter.RVCM_ERR_PARAMETER_CONFLICT The function received conflicting values forparameters. rvcm_Enable( ) received RV_FALSE as its requireOldMsgsparameter, and NULL as its name Parameter. A non- reusable name impliesa transient correspondent, which cannot have backlog messages.RVCM_ERR_FILE_IO_ERROR rvcm_Enable( ) encountered an error while openingthe ledger file. For example, an explicitly named directory does notexist. rvcm_SyncLedgerFile( ) encountered an error while writing theledger file. RVCM_ERR_FILE_NO_PERMISSION File access privileges areinsufficient for rvcm_Enable ( ) to open the ledger file.RVCM_ERR_FILE_NOT_LEDGER_OWNER The reusable name recorded in the filediffers from the name of this session. ryere_Enable ( ) stopped readingthe file. RVCM_ERR_CORRUPT_LEDGER_FILE The ledger file is corrupt.rvcm_Enable( ) could read only part of the ledger file intoprocess-based memory. Some information may be lost.

See Also

rvcm_ErrorText( ), below.

APPENDIX B: Distributed Queues (Programming Details for C Programmers)

This Appendix A provides programming details for C programmers wishingto implement Certified message Delivery. The Appendix provides, in TableA1, an overview listing of Certified's messaging Deliver Datatypes andFunctions. Each Datatype or Function is then described in greater detailwith Cross-references to related Datatypes or Functions.

As described above, Applications can use distributed queues forcertified delivery to one of n listeners (queue member sessions). Thesedistributed queue functions are typically used in combination withcertified message delivery.

Distributed Queue CAPI

The following Table BA summarizes the datatypes and functions in thedistributed queue C API. TABLE B1 Distributed Queues: Dataty yes andFunctions Item Description Page rvcm_EnableQueue( ) Enable a session asa 248 distributed queue member rvcm_rvcm_SetQueueAcceptTime( ) Set thequeue time 251 limit for task acceptance. rvcm_QueueAcceptTime( ) Returnthe queue time 253 limit for task acceptance. rvcm_SetQueueCompleteTime() Set the queue time limit 255 for task completion.rvcm_QueueCompleteTime( ) Return the queue time 257 limit for taskcompletion. rvcm_SetQueueListenerWeight( ) Set the listener weight 261of a queue member. rvcm_QueueListenerWeight( ) Return the listener 261weight of a queue member. rvcm_SetQueueListenerTasks( ) Set the listenertask 263 capacity of a queue member. rvcm_QueueListenerTasks( ) Returnthe listener task 266 capacity of a queue member. rvcm_Error DatatypeEnumerates 239 error codes for the certified message delivery API anddistributed queue API. rvcm_ErrorTest( ) Return a text string 244describing an error code

rvcm_EnableQueue( ) Function Declaration rvcm_Error rvcm_EnableQueue (  rv_Session session   rv_Name name,   unsigned long schedulerWeight,  unsigned long schedulerHeartbeat,   unsigned long schedulerActivation);

Purpose

Enable a session for certified message delivery as part of distributedqueue for one-of-n certified delivery.

Remarks

Each member of a distributed queue listens for the same subjects—yeteven when n members listen, for each inbound message (or task), exactlyone member processes the message.

Programs must call rvcm_EnableQueue( ) before any other calls related todistributed queues or certified listening.

Once a session becomes a queue member, it cannot resign membershipexcept with rv_Term( ).

Queue Member Roles

Each distributed queue member session has two distinct roles—as alistener, and as a potential scheduler.

In the listener role, queue member sessions support a limited subset ofcertified delivery calls: rvcm_ListeaSubject( ), rvcm_NoAutoConfirm( )and rvcm_Confirm( ). Queue member sessions do not support any othercertified delivery calls (in particular, calls associated with sendingcertified messages). However, they do support all standard system calls(for example, rv_Send( )).

System fault tolerance software maintains exactly one active schedulerin each queue: if the scheduler process terminates, another memberassumes the role of scheduler. The queue member session in the schedulerrole assigns inbound tasks to listeners in the queue. (A scheduler canassign tasks to its own listener component, but only does so when allother listeners are busy.)

Parameters Parameter Description session The call enables this session.Before this call, the session must not yet be enabled for deliverytracking. name The session becomes part of the distributed queue withthis reusable name. schedulerWeight Weight represents the ability ofthis session to fulfill the role of scheduler, relative to other membersof the same queue. The queue members use relative scheduler weightvalues to elect one member as the scheduler; members with higherscheduler weight take precedence. Acceptable values range from 1 to65535 (even though the parameter is declared as an unsigned long).schedulerHeartbeat The scheduler session sends heartbeat messages atthis interval (in milliseconds). All sessions in the queue must specifythe same value for this parameter. Acceptable values are the unsigned32-bit integers (except zero). schedulerActivation When the heartbeatsignal from the scheduler has been silent for this interval (inmilliseconds), the queue member with the greatest scheduler weight takesits place as the new scheduler. All sessions in the queue must specifythe same value for this parameter. Acceptable values are unsigned 32-bitintegers (except zero).

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_SESSION_ALREADY_ENABLEDrvcm_Enable() received a session that is already enabled for deliverytracking. It is illegal to enable a session more than once.RVCM_ERR_NO_MEMORY The function could not complete because the operatingsystem denied its request to allocate storage. RVCM_ERR_INIT_FAILURErvcm_EnableQueue() could not initialize either the certified delivery orfault tolerance components upon which it depends.

See Also rvcm_Enable( ), Appendix A rvcm_ListenSubject( ), Appendix A******* rvcm_SetQueueAcceptTime( ) Function Declaration #defineDEFAULT_ACCEPT_TIME (0) rvcm_Error rvcm_SetQueueAccepCTime (  rv_Session  session,   unsigned long acceptTime );

Purpose

Change the accept time parameter of a queue member session.

Remarks

When this session, acting as the scheduler, assigns a task to a listener(another queue member session), it sets a timer with this length (inmilliseconds). If the timer elapses before the scheduler receivesacceptance from the listener, the scheduler reassigns the task toanother listener.

Zero is a special value, which specifies no limit on the acceptancetime—that is, the scheduler does not set a timer, and does not reassigntasks.

Enabling a session as a queue member tacitly sets its accept timeparameter to DEFAULT_ACCEPT_TIME (zero).

Parameters Parameter Description session A session in a distributedqueue. acceptTime This value (in milliseconds becomes the new time limitfor acceptance of tasks. It must be less than the complete timeparameter (unless the complete time is zero).

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_ARG The function received anillegal argument. RVCM_ERR_SESSION_NOT_ENABLED The function received asession that is not enabled for delivery tracking.

See Also vcm_QueueAcceptTime( ), below rvcm_QueueAcceptTime( ) FunctionDeclaration #define DEFAULT_ACCEPT_TIME (0) rvcm_Errorrvcm_QueueAcceptTime (   rv_Session session,   unsigned long* acceptTime);

Purpose

Extract the accept time parameter of a queue member session.

Remarks

When this session, acting as the scheduler, assigns a task to a listener(another queue member session), it sets a timer for the accept time (inmilliseconds). If the timer elapses before the scheduler receivesacceptance from the listener, the scheduler reassigns the task toanother listener.

Zero is a special value, which specifies no limit on the acceptance time(the scheduler does not set a timer).

Enabling a session as a queue member tacitly sets its accept timeparameter to DEFAULT_ACCEPT_TIME (zero).

Parameters Parameter Description session A session in a distributedqueue. acceptTime This location receives the stored time limit (inmilliseconds) for acceptance of tasks.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully.

rvcm_Qz, QuoueAcceptTime( ) RVCM_ERR Code IndicatesRVCM_ERR_INVALID_SESSION The function received a session argument thatis not a valid rv_session (for example, NULL, or a session that hasalready terminated). RVCM_ERR_BAD_ARG The function received an illegalargument. RVCM_ERR_SESSION_NOT_ENABLED The function received a sessionthat is not enabled for delivery tracking.

See Also rvcm_SetQueueAccepcTime( ), above rvcm_SetQueueCompleteTime( )Function Declaration #define DEFAULT_COMPLETE_TIME (0) rvcm_Errorrvcm_SetQueueCompleteTime (   rv_Session   session,   unsigned longcompleteTime );

Purpose

Change the complete time parameter of a queue member session.

Remarks

When this session, acting as the scheduler, assigns a task to a listener(another queue member session), it sets a timer with this length (inmilliseconds). If the timer elapses before the scheduler receives acompletion message from the listener, the scheduler reassigns the taskto another listener.

Zero is a special value, which specifies no limit on the completion time(the scheduler does not set a timer).

Enabling a session as a queue member tacitly sets its complete timeparameter to DEFAULT_COMPLETE_TIME (zero).

Parameters Parameter Description session A session in a distributedqueue. completeTime This value (in milliseconds) becomes the new timelimit for completion of tasks. It must be greater than the accept timeparameter (unless the complete time is zero).

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_ARG The function received anillegal argument. RVCM_ERR_SESSION_NOT_ENABLED The function received asession that is not enabled for delivery tracking.

See Also rvcm_QueueCompleteTime( ), below rvcm_QueueCompleteTime( )Function Declaration #define DEFAULT_COMPLETE_TIME (0) rvcm_Errorrvcm_QueueCompleteTime (   rv_Session session,   unsigned long*completeTime );

Purpose

Extract the complete time parameter of a queue member session.

Remarks

When this session, acting as the scheduler, assigns a task to a listener(another queue member session), it sets a timer for the complete time(in milliseconds). If the timer elapses before the scheduler receives acompletion message from the listener, the scheduler reassigns the taskto another listener.

Zero is a special value, which specifies no limit on the completion time(the scheduler does not set a timer).

Enabling a session as a queue member tacitly sets its complete timeparameter to DEFAULT_COMPLETE_TIME (zero).

Parameters Parameter Description session A session in a distributedqueue. completeTime This location receives the stored time limit (inmilliseconds) for completion of tasks.

Errors RVCM_ERR Code Indicates RVCM_0K No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_ABG The function received anillegal argument. RVCM_ERR_SESSION_NOT_ENABLED The function received asession that is not enabled for delivery tracking.

See Also rvcm_SetQueueCompleteTime ( ), below rvcm_Errorrvcm_QueueCompleteTime ( ) Function Declaration #defineDEFAULT_COMPLETE_TIME (0) rvcm_Error rvcm_QueueCompleteTime (  rv_Session session,   unsigned long* completeTime );

Purpose

Extract the complete time parameter of a queue member session.

Remarks

When this session, acting as the scheduler, assigns a task to a listener(another queue member session), it sets a timer for the complete time(in milliseconds). If the timer elapses before the scheduler receives acompletion message from the listener, the scheduler reassigns the taskto another listener.

Zero is a special value, which specifies no limit on the completion time(the scheduler does not set a timer).

Enabling a session as a queue member tacitly sets its complete timeparameter to DEFAULT_COMPLETE_TIME (zero).

Parameters Parameter Description session A session in a distributedqueue. completeTime This location receives the stored time limit (inmilliseconds) for completion tasks.

Errors RVCM_ERR Code Indicates RVCM-ERR-INVALID-SESSION The functionreceived a session argument that is not a valid rv_Session (for example,NULL, or a session that has already terminated). RVCM-ERR-BAD-ARG Thefunction received an illegal argument. RVCM_ERR_SESSION_NOT_ENABLED Thefunction received a session that is not enabled for delivery tracking.RVCM_OK No error. The call completed successfully.

See Also rvcm_SetQueueCompeteTime ( ), above.rvcm_SetQueueListenerWeight( ) Function Declaration #defineDEFAULT_LISTENER_WEIGHT (1) rvcm_Error rvcm_SetQueueListenerWeight (  rv_Session   session,   unsigned long listenerWeight );

Purpose

Change the listener weight parameter of a queue member session.

Remarks

When the scheduler receives a task, it assigns the task to the availablelistener with the greatest listener weight.

A listener is considered available unless either of these conditions aretrue:

-   -   The pending tasks assigned to the listener exceed its task        capacity.    -   The listener session is the scheduler. (The scheduler assigns        tasks to its own listener only when no other listeners are        available.)

Enabling a session as a queue member tacitly sets its listener weightparameter to DEFAULT_LISTENER_WEIGHT (1).

Parameters Parameter Description session A session in a distributedqueue. listenerWeight This value becomes the new listener weight of thesession.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_Session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_ARG The function received anillegal argument. RVCM_ERR_SESSION_NOT_ENABLED The function received asession that is not enabled for delivery tracking.

See Also rvcm_QueueListenerWeight ( ), below. rvcm_QueueListenerWeight() Function Declaration #define DEFAULT_LISTENER_WEIGHT (1) rvcm_Errorrvcm_QueueListenerWeight (   rv_Session session,   unsigned long*listenerWeight );

Purpose

Extract the listener weight parameter of a queue member session.

Remarks

When the scheduler receives a task, it assigns the task lo the availablelistener with the greatest listener weight.

A listener is considered available unless either of these conditions aretrue:

-   -   The pending tasks assigned to the listener exceed its task        capacity.    -   The listener session is the scheduler. (The scheduler assigns        tasks to its own listener only when no other listeners are        available.)

Enabling a session as a queue member tacitly sets its listener weightparameter to DEFAULT_LISTENER_WEIGHT (1).

Parameters Parameter Description session A session in a distributedqueue. listenerWeight This location receives the current listener weightof the session.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_Session) for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_ARG The function received anillegal argument. RVCM_ERR_SESSION_NOT_ENABLED The function received asession that is not enabled for delivery tracking.

See Also rvcm_SetQueueListenerWeight ( ), above.rvcm_SetQueueListenerTasks( ) Function Declaration #defineDEFAULT_LISTENER_TASKS (1) rvcm_Error rvcm_SetQueueListenerTasks (  rv_Session       session,   unsigned long   listenerTasks );

Purpose

Change the listener tasks parameter of a queue member session.

Remarks

Task capacity is the maximum number of tasks that a listener can accept.When the number of accepted tasks reaches this maximum, the listenercannot accept additional tasks until it completes one or more of them.

When the scheduler receives a task it assigns the task to the listener(a queue member) with the greatest listener weight—unless the pendingtasks assigned to that listener exceed its task capacity. When thepreferred listener has too many tasks, the scheduler assigns the newinbound task to the listener with the next greatest listener weight.

Enabling a session as a queue member tacitly sets its listener tasksparameter to DEFAULT_LISTENER_TASKS (1).

Programmers can tune task capacity based on two factors:

Multi-tasking program on multiprocessing hardware.

-   -   On a multiprocessing computer, a multi-threaded program that        devotes n threads and n processors to inbound tasks has task        capacity n.

Communication time lag.

-   -   In most distributed queue applications, the communication time        is an insignificant fraction of the task turnaround time. That        is, the time required to assign a task and signal its completion        is very small compared to the time required to process the task        itself For example, when average task turnaround time is 2000        milliseconds, of which communication time contributes only 10        milliseconds to the total, then task capacity is the same as the        number of processors or threads.    -   However, in some situations communication time can be        significant--for example, when the queue members are distributed        at distant sites connected by a Wide Area Network (WARN). When        communication time is significant, the meaning of task capacity        changes; instead of signifying the number of tasks that a        listener can process concurrently, it signifies the number of        tasks that can fill the listener's capacity despite the        communication time lag. For example, when the average task        turnaround time is 1500 milliseconds, of which the average task        processing time contributes 1000 milliseconds to the total, then        setting the task capacity to 3 minimizes the listener's idle        time between tasks.    -   When tuning task capacity to compensate for communication time        lag, balance is critical. Underloading a listener (by setting        its tasks capacity too low) can cause the listener to remain        idle while it waits for the schedule to assign its next task.        Conversely, overloading a listener (by setting its task capacity        too high) can cause some assigned tasks to wait, while other        listeners that might have accepted those tasks remain idle.

Parameters Parameter Description session A session in a distributedqueue. listenerTasks This value becomes the new listener task capacityof the session. The value must be 1 or greater.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_Session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_ARG The function received anillegal argument. RVCM_ERR_SESSION_NOT_ENABLED The function received asession that is not enabled for delivery tracking.

See Also rvcm_QueueListenerTasks ( ), below. rvcm_QueueListenerTasks( )Function Declaration #define DEFAULT_LISTENER_WEIGHT (1) rvcm_Errorrvcm_QueueListenerTasks (   rv_Session session,   unsigned long*listenerTasks );

Purpose

Extract the listener tasks parameter of a queue member session.

Remarks

Task capacity is the maximum number of tasks that a listener can accept.When the number of accepted tasks reaches this maximum, the listenercannot accept additional tasks until it completes one or more of them.

When the scheduler receives a task, it assigns the task to the listener(a queue member) with the greatest listener weight—unless the pendingtasks assigned to that listener exceed its task capacity. When thepreferred listener has too many tasks, the scheduler assigns the newinbound task to the listener with the next greatest listener weight.

Enabling a session as a queue member tacitly sets its listener tasksparameter to DEFAULT_LISTENER_TASKS (1).

Parameters Parameter Description session A session in a distributedqueue. listenerTasks This location receives the current listener taskcapacity of the session.

Errors RVCM_ERR Code Indicates RVCM_OK No error. The call completedsuccessfully. RVCM_ERR_INVALID_SESSION The function received a sessionargument that is not a valid rv_session (for example, NULL, or a sessionthat has already terminated). RVCM_ERR_BAD_ARG The function received anillegal argument. RVCM_ERR_SESSION_NOT_ENABLED The function received asession that is not enabled for delivery tracking.

See Also

rvcm_SetQueueListenerTasks( ), above.

1. In a computer-based publish/subscribe system, a method forcommunicating a target message from a publisher application to areceiving member of a distributed queue of subscriber applications,wherein the distributed queue of subscriber applications comprises aplurality of members, the method comprising: an initiating member of thedistributed queue of subscriber applications subscribing to receivemessages pertinent to a subject, wherein the target message is pertinentto the subject; a detecting member of the distributed queue ofsubscriber applications detecting the target message, wherein the targetmessage was sent from the publisher application; and the receivingmember of the distributed queue of subscriber applications receiving thetarget message.
 2. The method of claim 1, wherein the initiating member,the detecting member, and the receiving member are all the same memberof the distributed queue of subscriber applications.
 3. The method ofclaim 1, wherein the target message is received by no more than onemember of the distributed queue of subscriber applications.
 4. Themethod of claim 1, wherein the receiving member of the distributed queueof subscriber applications comprises the member of the distributed queueof subscriber applications determined to be the member most capable ofprocessing the message.
 5. The method of claim 4, wherein the member ofthe distributed queue of subscriber applications determined to be themember most capable of processing the message is determined by ascheduling member of the distributed queue of subscriber applications,wherein the scheduling member routes the target message to the receivingmember of the distributed queue of subscriber applications, and whereinthe scheduling member receives message processing capability informationfrom the plurality of members of the distributed queue of subscriberapplications.
 6. The method of claim 5, wherein the scheduling member ofthe distributed queue of subscriber applications comprises the member ofthe distributed queue of subscriber applications determined to be themember most capable of performing tasks associated with the schedulingmember.
 7. The method of claim 5, wherein the scheduling membercommunicates heartbeat messages to the plurality of members of thedistributed queue of subscriber applications, the heartbeat messagesindicating that the scheduling member is capable of performing tasksassociated with the scheduling member.
 8. The method of claim 7,wherein, upon the scheduling member ceasing to communicate heartbeatmessages to the plurality of members of the distributed queue ofsubscriber applications, a new scheduling member is selected, the newscheduling member comprising the member of the distributed queue ofsubscriber applications determined to be the member most capable ofperforming tasks associated with the scheduling member.
 9. The method ofclaim 1, further comprising: a registering member of the distributedqueue of subscriber applications registering with the publisherapplication for certified delivery of messages pertinent to the subject;an accepting member of the distributed queue of subscriber applicationsreceiving an acceptance of registration for certified delivery from thepublisher application; and after the target message is received, anacknowledging member of the distributed queue of subscriber applicationsacknowledging receipt of the target message to the publisherapplication.
 10. The method of claim 9, wherein the initiating member,the registering member, the accepting member, the detecting member, thereceiving member, and the acknowledging member are all the same memberof the distributed queue of subscriber applications.
 11. A distributedqueue of subscriber applications for receiving a target message from apublisher application in a computer-based publish/subscribe system, thedistributed queue of subscriber applications comprising a plurality ofmembers, the plurality of members comprising: an initiating member,wherein the initiating member subscribes to receive messages pertinentto a subject, wherein the target message is pertinent to the subject; adetecting member, wherein the detecting member detects the targetmessage, and wherein the target message was sent from the publisherapplication; and a receiving member, wherein the receiving memberreceives the target message.
 12. The distributed queue of subscriberapplications of claim 11, wherein the initiating member, the detectingmember, and the receiving member are all the same member.
 13. Thedistributed queue of subscriber applications of claim 1 1, wherein thetarget message is received by no more than one member.
 14. Thedistributed queue of subscriber applications of claim 11, wherein thereceiving member comprises the member determined to be the member mostcapable of processing the message.
 15. The distributed queue ofsubscriber applications of claim 14, wherein the member determined to bethe member most capable of processing the message is determined by ascheduling member, wherein the scheduling member routes the targetmessage to the receiving member, and wherein the scheduling memberreceives message processing capability information from the plurality ofmembers.
 16. The distributed queue of subscriber applications of claim15, wherein the scheduling member comprises the member determined to bethe member most capable of performing tasks associated with thescheduling member.
 17. The distributed queue of subscriber applicationsof claim 15, wherein the scheduling member communicates heartbeatmessages to the plurality of members, the heartbeat messages indicatingthat the scheduling member is capable of performing tasks associatedwith the scheduling member.
 18. The distributed queue of subscriberapplications of claim 17, wherein, upon the scheduling member ceasing tocommunicate heartbeat messages to the plurality of members, a newscheduling member is selected, the new scheduling member comprising themember determined to be the member most capable of performing tasksassociated with the scheduling member.
 19. The distributed queue ofsubscriber applications of claim 11, further comprising: a registeringmember, wherein the registering member registers with the publisherapplication for certified delivery of messages pertinent to the subject;an accepting member, wherein the accepting member receives an acceptanceof registration for certified delivery from the publisher application;and an acknowledging member, wherein the acknowledging memberacknowledges receipt of the target message to the publisher applicationafter the target message is received.
 20. The method of claim 19,wherein the initiating member, the registering member, the acceptingmember, the detecting member, the receiving member, and theacknowledging member are all the same member of the distributed queue ofsubscriber applications.